Technotools

home *** CD-ROM | disk | FTP | other *** search

/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / editors / tscredd2 / scrdisk5.exe / arc / TUTORPT3.DOC < prev

Wrap

Text File | 1990-04-29 | 115KB | 2,838 lines

Page I-11 TURBO SCREDIT TUTOR PART III - Programming with Turbo ScrEdit. Introduction to Turbo ScrEdit Tutor Part III.........T-3.1 What you need before you get started.................T-3.1 A MINIMUM coding example.............................T-3.3 Programs generated by Turbo ScrEdit (G Menu Option)..T-3.5 Generating a source code file.....................T-3.6 Understanding the source code generated...........T-3.7 Compiling and running the generated programs......T-3.14 A look at ScrDemo.Exe................................T-3.15 Option 1 - A data entry example...................T-3.20 S_ClearScreen and the SET command.............T-3.21 S_EnterAsTab..................................T-3.24 S_IsDupe, S_SetDupe, S_ClearDupes.............T-3.25 Changing the value of a DUPE field............T-3.26 Sound ON/OFF..................................T-3.27 Auto Help ON/OFF..............................T-3.28 Auto Validate ON/OFF..........................T-3.28 Changing message line colors..................T-3.29 Option 2 - Demo of MOUSE functions................T-3.30 S_MouseInstalled..............................T-3.30 S_ActivateMouse...............................T-3.30 S_SetMouseEvent...............................T-3.30 S_SetMouseRange...............................T-3.31 S_MsRow & S_MsCol.............................T-3.31 S_ShowMouse...................................T-3.31 S_ResetMouseFlags.............................T-3.32 S_MouseEvent (S_Ms->MouseEvent for C).........T-3.32 S_AnalizeMouse................................T-3.32 S_HideMouse...................................T-3.38 S_DisableMouse................................T-3.38 Option 3 - Customizing screen colors..............T-3.38 S_ChangeScreenColors..........................T-3.39 S_ChangeFieldColors...........................T-3.40 S_StoreColorChanges...........................T-3.41 Options 4 through 9...............................T-3.42 Page T-3.1 ** Turbo ScrEdit Tutor ** Copyright(C) 1989, by iHn Systems Introduction to Turbo ScrEdit Tutor Part III ----------------------------------------------------------------- In PART ONE you learned how to create a screen file, create and edit screens, compile a screen, change the order that the screens fields are processed, change the field's display and prompt color assignments, test a screen, and finally, how to tell scredit to create the source code needed to use the screen file. In PART TWO you learned how to use Turbo ScrEdit's field processing language, and how use the screen test facilities. In PART THREE we are going get acquainted with some programming examples that demonstrate how to write programs that take full advantage of all Turbo Scredit's screen handling and data editing features. We will look at some example programs that range from very simple to very complex. These programming examples use Turbo ScrEdit screens, mouse procedures. We will also take a closer look at some of the ways that you can use ScrEdit's field processing language to edit values keyed into screen fields, set initial values, and use edit masks. Forgive me if explain things that seem pretty basic to you. Or if I talk to you as though you don't know a lot about programming in your language. I have found that many people ordering Turbo ScrEdit say that they are just getting started with programming. The approach I am taking here is for their benefit. If you are a seasoned programmer feel free to skip over what you don't need. What you need to before we get started. ----------------------------------------------------------------- Before we get started you must have already created the "unit" files or the C "object code library" files as described on pages 4, 5, and 6 of the "Turbo ScrEdit Reference Manual". You will also need to have the following source code files available to be edited, compiled, and run. Files need for this part of the tutor. ------------------------------------------------------------ Smallest.Pas or Smallest.C Smallest.Prj ScrDemo.Pas or ScrDemo.C ScrDemo.Prj ScrDemo.Scr DemoWind.Exe Preparing the screens to be used. ------------------------------------------------------------ Before we can begin compiling and running the demonstration programs we will need to use the Turbo ScrEdit Screen Editor to compile the screens in the screen file "ScrDemo.Scr". LOAD AND RUN TSCREDIT Page T-3.2 PRESS F1 AND TYPE "SCRDEMO" Once you have loaded the file "ScrDemo" you will want to compile each screen in the file using the F4 menu option. PRESS F4 ON THE FIRST SCREEN "DEMO_MENU". SELECT THE OPTION FOR YOUR COMPILER AND PRESS "Y' TO CONTINUE. PRESS ESC Now we should be back to the main menu. Turbo ScrEdit has just created the screen record definitions for "Demo_Menu". PRESS HOME to scroll to the next screen "Demo_Screen". PRESS F4 again to compile this screen and repeat this process until you have compiled all the screens in this screen file. When you are finished compiling all the screens in the file, press the ESC key to exit back to DOS. Page T-3.3 Minimum coding example ----------------------------------------------------------------- The source files "Smallest.Pas" and "Smallest.C" have been included in your Turbo ScrEdit package. We are going to begin by looking at just how little effort it takes to get a screen up and running. Normally you would create a screen of your own that pertains to the application that you intend to develop, but for this example we are going to use a screen that is stored in the screen file "ScrDemo.Scr." Load and run your Turbo Language programming environment. Load one of the files "Smallest.Pas" or "Smallest.C" depending on the language that you are using. You should now be in your program editor. The entire "Smallest.?" source file should be visible on your screen. Lets take a line by line look at this little program. Pascal C ----------------------------- --------------------------- =1> Uses ScrEdit; #include "ScrEdit.H" =2> {$I YourFile.001} #include "YourFile.001" =3> void main() =4> Begin { =5> S_Init(); =6> S_OpenScreenFile('ScrDemo); S_OpenScreenFile("ScrDemo"); =7> Initialize_Dupe_Demo_Buf; Initialize_Dupe_Fields_buf; =8> S_LoadScreen('Dupe_Fields'); S_LoadScreen("Dupe_Fields"); =9> Repeat do{ =10> S_ReadScreen; S_ReadScreen(); =11> If S_Enter Then if (S_Enter) =12> S_UserMsg := strcpy(S_UserMsg, ' PROCESS SCREEN '; " PROCESS SCREEN "); =13> } =14> Until S_Esc; while (!S_Esc); =15> S_CloseScreenFile; S_CloseScreenFile(); =16> End. } ------------------------------ --------------------------- =1> The first statement includes the unit files or the object code library headers that contain the Turbo ScrEdit procedures prototypes. =2> This include statement will copy the screen buffer definitions for "ScrDemo.004" or the screen named "Dupe_Fields" into the program. This will be the screen we will experiment with first. =3> Statement number 3 defines "MAIN" and is required by C. =4> Begin the procedure. =5> Turbo Pascal is self initializing, but Turbo C requires that you perform a call to S_Init to initialize the Turbo ScrEdit interface module. ** DON'T ** forget to make this call as one of the first things done in your program. If Page T-3.4 you call a Turbo ScrEdit procedure before initializing, your computer will most likely lock up when Turbo ScrEdit starts loading values into memory addressed by pointers that have not been initialized. =6> Next we will open the screen file "ScrDemo" and prepare it to be used by our program. =7> Now that the screen file is open we can load the screen and display it to the video screen. =8> Next a loop begins. =9> A call is made to S_ReadScreen. Turbo ScrEdit will now accept data into the screen that has been displayed until the ENTER key or some other special key is pressed. =10> When the one of the special keys are pressed, control returns to this point in the program. At this point we could check for any key that has been press. In this example I am checking to see if the enter key has been pressed. =11> If the Enter key has been pressed =12> the message " PROCESS SCREEN " is moved to the user definable message variable. The next time a call is made to S_ReadScreen, S_ReadField, or S_ReadKey, the message will be displayed. =13> C specific end of do/while statements. =14> We see that the loop is to be repeated until the user of the program presses the ESC key. =15> When the user presses the ESC key, the screen file is closed. =16> Execution ends. MAKE SURE THAT THIS PROGRAM COMPILES SUCCESSFULLY AND RUNS BEFORE YOU CONTINUE WITH THIS TUTOR. Turbo Pascal: This program should compile and run if you have done the following: 1 - You have created the "unit" files mentioned in the introduction and moved them to your unit directory. 2 - Set OPTION/LINKER/LINK BUFFER to DISK 3 - Set OPTION/DIRECTORIES/UNIT to the disk directory where you have stored "Scredit.Tpu", "ScrMouse.Tpu", "Windows.Tpu". 4 - Set COMPILE/DESTINATION to DISK 5 - Set COMPILE/PRIMARY FILE to "Smallest.Pas" With these setting you should be able to compile and execute this program. Page T-3.5 Turbo C: This program should compile and run if you have done the following: 1 - Edit the project file Smallest.Prj and add the drive, path and library name that you will be using. The project file is set up to use the MEDIUM memory model so change it to use the memory model of your choice: (MEDIUM) screditM.lib, (COMPACT) screditC.lib, (LARGE) screditL.lib, or (HUGE) screditH.lib. The current project file reads: smallest screditm.lib You might change it to: smallest C:\TC\screditM.Lib 2 - Set PROJECT/PROJECT NAME to "scrdemo.prj" 3 - Set OPTION/COMPILER/MODEL to the same memory model you selected the library for in the project file. 4 - Set COMPILE/PRIMARY C FILE: to "smallest". With these setting you should be able to compile and run this example program. The purpose of this example was to show you how little coding is required to access a screen file and display a screen. We will take a closer look at how this screen is used when we look at the demo program ScrDemo. When you are finished experimenting with this program exit back to DOS and resume with the next section of this tutor that describes source files generated by Turbo ScrEdit. Programs Generated by Turbo ScrEdit ----------------------------------------------------------------- Next we will take a look the program that Turbo ScrEdit would generate for you to handle the screens in the ScrDemo.Scr screen file. As we begin this section of the tutor, you should be at the DOS prompt. It is important to understand that when Turbo ScrEdit generates a source file it always names it the same name as the screen file that the screens are stored in with a extension of '.Pas' for Pascal source code or ".C" for C source code. Next we are going to use Turbo ScrEdit's main menu "G" option to generate a program source file that will access all the screens stored in the screen file "ScrDemo.Scr". Turbo "C" users - since we are going to generate a skeleton file for the screens in "ScrDemo.Scr" you will need Page T-3.6 to rename the file "SCRDEMO.C" to "SCRDEMO.OLD". Otherwise, Turbo ScrEdit will overlay our other demonstration program's source code with the code that we are about to generate. We are ready to begin. Generating a source code file. ----------------------------------------------------------------- Run Turbo ScrEdit and load the screen file "ScrDemo" as the work file. PRESS "G" SELECT THE COMPILER THAT YOU ARE USING. PRESS TAB PRESS "N" So all comments will not be supressed durring code generation, but will be included in the source file generated. PRESS "N" We want the screen buffer files to be included at compiler time for this example. PRESS "M" We will use mixed upper and lower case for this example. Next we must tell Turbo ScrEdit where the skeleton file is located that is used to generate source code. If the default directory displayed is not correct then correct it by typing in a new drive and path. Next we must tell Turbo ScrEdit which screens we want the program that is going to be generated to be able to access. You will notice that a light bar is highlighting the screen name "Demo_Screen". PRESS DOWN ARROW A COUPLE OF TIMES. The light bar moves down a name each time the down arrow is pressed. PRESS THE UP ARROW AND MOVE THE LIGHT BAR BACK TO THE TOP NAME IN THE WINDOW. PRESS THE HOME KEY. The HOME key places a marker next to the screen name. This marker means that the screen to the left of it will be one of the screens that the new program will access. Notice that the light bar has moved to the next screen name. PRESS UP ARROW Page T-3.7 PRESS THE END KEY. The marker is removed and the light bar has moved to the next screen name. PRESS THE HOME KEY ON EACH OF THE SCREEN NAMES IN THE WINDOW. For the purpose of this example we want all the screens in this screen file to be marked. PRESS ENTER. A message "** GENERATING SOURCE CODE **" appears on the message line as Turbo ScrEdit generates the new program file. If you are using "C" and you did not rename the file ScrDemo.C to ScrDemo.Old, you will get warning that Turbo ScrEdit is going to overlay the original source file with the new one it is about to generate. When the message disappears Turbo ScrEdit will return to the main menu. PRESS ESC to exit Turbo ScrEdit. Print a copy of the program that was just generated, "ScrDemo.C" or "ScrDemo.Pas", and a copy of "Skeleton.C" or "Skeleton.P" depending of which compiler you are using. We will examine the skeleton file and what Turbo ScrEdit added to it when the new program file was generated. A look at a program file generated by Turbo ScrEdit. ---------------------------------------------------------------- As you begin this section of the tutor, you should have: 1 - The source file that we just generated, "ScrDemo.C" or "ScrDemo.Pas" loaded into your programming editor, with the first few lines of code visible on the video. 2 - The printed listing of the skeleton file "Skeleton.C" or "Skeleton.Pas". The program file that Turbo ScrEdit generates is intended to be a launching platform for your new applications. The discussion that follows will help you understand the way Turbo ScrEdit uses the skeleton file. The source code in this file has been divided into sections with labels surrounded by "**". In the text that follows I will describe the code that is inserted by Turbo ScrEdit following each of these labels. As you read the descriptions that follow, locate each label in the skeleton file listing. Then locate the same label in the program you have loaded into you text editor and see what Turbo ScrEdit has inserted in the text. Page T-3.8 You may modify the original skeleton file if you wish. DO NOT change any line that has words surrounded by "**". Turbo ScrEdit Locates these key words and inserts the code needed for processing the particular screen file. You may change anything else that you wish. If you remove any of the text markers used by Turbo ScrEdit it will not insert the code that it otherwise would into the file. Locate "**Version**". It is the fist key word in the file. Pascal -------------------------------------------------------------- Turbo ScrEdit has added a "USES" statement here. For C: -------------------------------------------------------------- Turbo ScrEdit has added a #include statement here that will copy in the Turbo ScrEdit header file "ScrEdit.H". Locate "**Buffers**". When you compile a screen using the "F4" option from the Turbo ScrEdit main menu, a small file is created that contains the record definition for the screen and the screen initialization procedure. This is where these screen buffers and initialization procedures will be placed in the program. Turbo ScrEdit allows you to select whether the buffer modules are to be copied into the code at this point or included at compile time by using $I or #include statements. We see that Turbo ScrEdit has inserted five of these include statements into the "ScrDemo" source file. Locate "**User Variables**" ScrEdit will not place any additional code here. You may define your program's global variables and procedures beginning here. Locate "** Example of loading and displaying screens **" This section of code is used only for switching from screen to screen when the F1 key is pressed. You may convert this into a working procedure for your programs by changing the procedure to read: Page T-3.9 For Pascal: Procedure Load_Screen; Begin Case S_Num of Don't change anything between Case and End; End; End; For C: void Load_Screen(); { switch (S_Num) { Don't change anything between switch and }; } } If you make this change you can load a screen by assigning "S_Num" one of the screen numbers from the case statement that corresponds to the screen name that you want loaded. Be aware that Turbo ScrEdit will change the value of S_Num to the actual screen number as it appears in the screen file index. ** NOTE ** the field S_Num is defined in ScrEdit.pas. All of the fields that have been defined for use with Turbo ScrEdit procedures start with "S_". Try not to use the "S_" naming convention for your programs variables to avoid having conflicts with Turbo Scredit. Locate "**ScreenFileName**" Turbo ScrEdit places the statement here that will open the screen file. Turbo C -------------------------------------------------------------- An important thing to know about this call is that it turns the system cursor off. If the program ends abnormally the cursor may be left off. To insure that the cursor is not left off, always call S_CloseScreenFile at the end of your program. Cursor.exe has be included in the Turbo ScrEdit package and can be ran to restore the system cursor. Turbo Pascal -------------------------------------------------------------- Turbo ScrEdit handles abnormal ends for pascal. Page T-3.10 Locate "**InitRoutines**" Turbo ScrEdit will insert calls to all the screen initialization procedure here for each of the screens selected to be accessed by this source file. After the screen file is opened the screen buffer initialization procedures must be performed. There will be a procedure for each of the screens that were selected in the screen file when the source code was generated. ** IMPORTANT NOTE ** if for some reason the initialization procedures are not performed, your program will malfunction. Data will not be moved to and from the screen properly. In some cases your program will hang the system because data is being move to memory locations addressed by pointers that have incorrect values. IN MOST CASES IF YOU HAVE PROBLEMS USING TURBO SCREDIT THIS WILL BE THE CAUSE. Locate "**System Switches**" This is where the global variables are being assigned values. Each of the fields listed here are assigned default values by Turbo ScrEdit when it is initialized. They are included here to help you understand that you can change these fields values to customize these features. You will find a complete description of each of these fields in the programmers reference manual. Any values that you may assign here will override the default values. Look up each of these variables in the programmers reference manual for a description of there function. Also you may experiment by changing them and recompiling this program and running it. Locate * 1st Example Code * This code initializes the pointers used to control the next screen to be loaded by the demonstration part of this program. You will want to delete these lines when you build your own program. The variable Demo_Mode is set to 1 by default to use the full screen read mode. See the description of "Demo Mode 1". Changing Demo_Mode to 2 will change the way that the program reads the screen fields from full screen mode to individual field mode. See the description of "Demo Mode 2". There are four methods supported by Turbo ScrEdit to process your screens. S_READKEY - returns a single key stroke in S_Ch and/or sets key flags. Page T-3.11 S_READFIELD - reads data into one field on the screen and sets key flags. S_READSCREEN - reads data into all the data entry fields on a screen and sets key flags. S_NEXTKEY - same as S_READKEY only no user messages are displayed on the bottom line of the display. In fact user message are discarded by this procedure. Locate "** Demo mode 1 - Full Screen Modes **" ----------------------------------------------------------------- The "IF" statement here is only needed to make the example of using S_READSCREEN work for demonstration mode 1. If you decide to use the full screen mode in your working program the code will look like this: For Pascal: S_READSCREEN; For C: S_ReadScreen(); When you call S_READSCREEN a number of things happen. - Any values that have been moved to fields in the screen record are displayed on the screen. (See the examples in the discussion on using "ScrDemo" that follows for more details.) - If the field "S_UserMsg" has been assigned a message it is displayed on the bottom line of the screen. - If S_Point has been assigned a screen field number, data entry will begin on the specified field. If S_Point is set to a display only field or a non-existent field, Turbo ScrEdit will advance to the next data entry field on the screen. If the screen has no fields Turbo ScrEdit calls S_READKEY and will return when the next key is pressed. The value of the key pressed is returned in the character field S_Ch. If the screen has only "display only" fields on it Turbo ScrEdit will call S_READKEY and return when the next key is pressed. If the screen has data entry fields on it, Turbo ScrEdit will accept data into the fields until a special keystroke is detected. See "* special key testing *" for more info on what special keys are. - When the ENTER key is pressed the entire screen is returned to your program. Any field validation specifications that have been defined for the fields on the screen are only considered when ENTER is pressed. Page T-3.12 Locate "** Demo Mode 2 **" ----------------------------------------------------------------- This code is intended to illustrate how to process a screen reading a single field at a time. When your program needs to have control between each field that the user keys you can use this method. Most of what you see in this code can be removed when you use it in a program. The Code that you would use will look like this: For Pascal: S_Point := field number; S_READFIELD; For C: S_Point = field number; S_ReadField(); The field number that S_POINT is assigned can be found on the screen listing that is produced using the F5 option of Turbo ScrEdit's main menu. If you don't have a printer you can number the fields with paper and pencil. Fields are numbered as they occur on the screen left to right and top to bottom beginning with 1 in pascal and 0 in C. When you call S_READFIELD a number of things happen. - If you have set S_POINT to a non-existent field, a dupe field, or a display only field an error message will be displayed. Remember when you use this method of processing a screen you are taking responsibility to direct Turbo ScrEdit to the field that you want used. - Any values that have been moved to fields in the screen record are displayed on the screen. - If the field S_UserMsg has been assigned a message it is displayed on the bottom line of the screen. - Turbo ScrEdit then prompts the user to enter data into the field. Turbo ScrEdit will continue to accept keystrokes into the field until one of the following occurs: 1 - Any of the special keys are pressed. See the section labeled "* special key testing *" for more info on what special keys are. 2 - The Field is filled with keystrokes. 3 - The Left or Right arrows are used to move the cursor out of the field at either the left or right side. 4 - The ENTER key is pressed. Page T-3.13 The field validation statements that are assigned to a field will only be used to test the contents of a field when conditions 2, 3, or 4 occur. *** IMPORTANT NOTE *** Remember that when the special keys are pressed, data entry ends, Turbo ScrEdit DOES NOT perform field validation, control returns immediately to your program. Don't use the data returned in the field unless your screen does not have field validation statements assigned to the fields, or your program verifies that the data is valid. Locate "** Example code for demonstration mode **" This code can be deleted and is only used to demonstrate using S_READKEY and providing a generic way of switching screens. In most cases you will use S_READKEY to prompt your user for a response. You could do something like this: Pascal: Repeat S_UserMsg := 'Delete this record Y/N'; S_ReadKey; Until UpCase(S_Ch) In['Y','N']; C: do{ strcpy(S_UserMsg,"Delete this record Y/N"); S_ReadKey(); }while ((!toupper(S_Ch)=='Y')||(!toupper(S_Ch)=='N')); In this example several things happen: - The contents of the screen record are moved to the screen. - The message assigned to S_UserMsg is displayed on the bottom line of the screen. - Turbo ScrEdit waits until a key is pressed, and then returns the keystroke in S_CH. This example will continue prompting and displaying the message until either "Y" or "N" is pressed. S_READKEY does not have any connection with screen fields, the key pressed is returned to your program but not displayed on the screen. Page T-3.14 Locate "** Special Key Testing **" This code demonstrates the entire spectrum of special key strokes and combinations of key strokes that you can test for. The best way to understand this code is to try each condition when you compile and run this program. Locate * Closing the screen file **" Turbo C users: If your program ends without closing the screen file the system cursor will be left off. Pascal users: The Pascal version of the Turbo ScrEdit interface will automatically do the house keeping for you when your programs ends normally or abnormally. That concludes our look at a source code file generated by Turbo ScrEdit's main menu "G" option. Compiling and running the generated programs. ----------------------------------------------------------------- Then next step is to compile and run the program and see how it actually works. Turbo Pascal ----------------------------------------------------------------- Before you try to compile and run this program be sure that the OPTION/DIRECTORY/UNITS search paths include the directory where you have stored "ScrEdit.Tpu". Also be sure that "ScrEdit.Pas" is not in the current director with the "ScrDemo" source files. You may now compile and run the program. Turbo C ----------------------------------------------------------------- Modify the project file "ScrDemo.Prj" so the compiler can locate the Turbo ScrEdit Interface library file "ScrEdit.Lib". The file now reads: scrdemo scrdemol.lib You might modify it to read like: scrdemo C:\TC\LIBS\scrdemol.lib Next set the OPTIONS/COMPILER/MODEL to LARGE. (You can use any model that you wish, MEDIUM, COMPACT, LARGE, or HUGE. Page T-3.15 Just be sure that it is the model that matches the library type specified in the project files "ScrDemo.Prj". Next set PROJECT/PROJECT NAME to "SCRDEMO.PRJ" Next set COMPILE/PRIMARY C FILE to "ScrDemo.C". You may now compiler and run the example program. If the program fails to compile review the instructions for your particular language and check each setting. If everything looks ok then go back and try compiling the "Smallest.Exe" program again. If "Smallest.Exe" compiles successfully, then ScrDemo should also compile. If "Smallest.Exe" will not compile and run then check that you have set everything up according to the instructions. If you still have problems you may want to call iHn Systems during the specified hours for assistance. Assuming that all has gone well and this example is executing, continue on. PRESS F1 to switch screens. You may want to recompile with the debugger active and follow the logic through the example code. To see how the special key testing is done, try typing unusual CTRL key combinations and identify in the code how it is testing for ALT and CTRL key combinations. Try turning CAPS LOCK, NUM LOCK, SCROLL LOCK, and INSERT MODE on and off while pressing other keys. This will show you how you can identify in your program the current status of the system toggle keys. This concludes the section that examines the programs that Turbo ScrEdit will generate for you. A look at ScrDemo.Exe. ---------------------------------------------------------------- In this section of the tutor we will walk through ScrDemo the main demonstration program supplied with Turbo ScrEdit. The program ScrDemo has been supplied to serve as a programming example that uses almost every procedure and function in the Turbo ScrEdit interface modules. This program has served as the "Test Program" used here at iHn Systems to test the Turbo ScrEdit interface modules as they were developed. The files "ScrDemo.C" and "ScrDemo.Pas" that came in your Turbo ScrEdit package contain the source code for the file "ScrDemo.EXE." The previous examples were intended to help you get comfortable with writing your own programs that use Turbo ScrEdit screens. This part of the tutor is intended to give you a closer look at Page T-3.16 the syntax and usage of the features and procedures of the Turbo ScrEdit interface module. This will include looking at a example data entry screen, interacting with the mouse, and programmatically changing screen color assignments, and much more. *** Turbo C users *** If you are working with Turbo C, delete the file "ScrDemo.C" and rename the version we stored earlier in the tutor as "ScrDemo.Old" back to "ScrDemo.C". Your will need the following for this example: A print copy of the files "ScrDemo.C" or "ScrDemo.Pas" depending on the compiler that you are using. Copy the following files into your work area on your system: Pascal C --------------------- ------------------ ScrDemo.P ScrDemo.C ScrDemo.Scr ScrDemo.Scr ScrDemo.Prj DemoWind.Exe You should already the following files from previous discussions: ScrDemo.001 ScrDemo.002 ScrDemo.003 ScrDemo.004 ScrDemo.005 If you do not have these files in the current work directory, load "ScrDemo.Scr" into the Turbo ScrEdit screen editor and re-compile all the screens using the F4 menus option. ** Turbo C users ** You will also want to use the project file that we created in the last example. Make sure that you OPTION/COMPILER/MODEL is still set to match the memory model of the library specified in the project file. Next load your compiler and the compile and run ScrDemo. You should now be setting at your computer with this tutor of course, the listing of the pascal or C version of ScrDemo opened to page 1, and the ScrDemo menu visible on you video monitor. Page T-3.17 An overview of the source code. ---------------------------------------------------------------- The source listing has been divided in sections. For instants, on the first page you will see some comments that reads: *********************************** MENU OPTION 1 (Example data entry screen) Section 2 of the Turbo ScrEdit Tutor Describes this portion of code. *********************************** Go ahead a flip through the code, you will find other places in the code that have similar markers. Locate the last text marker "PROGRAM BEGINS HERE" in the listing. It will be clear at the end on the last page of the source file. PROGRAM BEGINS HERE This is where it all begins, so lets follow the logic. First ScrDemo_Init is called. Look back in the code and locate this procedure, but keep a marker here where the program begins, we will want to turn back to this point in a minute. Locate ScrDemo_Init in the source listing; -------------------------------------------------------------- The first action of this procedure is to open the screen file "ScrDemo.Scr". Next the screen buffers are initialized. These are the steps that should always be done as one of the first actions performed in your program. ** IMPORTANT CONCEPT ** 1 - The screen file should always be opened before the screen buffers are initialized. 2 - EVERY TIME A SCREEN FILE IS OPENED, it's screen's buffers must be initialized. If you close a screen file and re- open it you must re-initialize all the screen buffers. ** ** ** ** ** ** ** ** If you are going to have trouble using Turbo ScrEdit, most likely it will be because you did not open and initialize the screen file and buffers in the right sequence. Next we see Turbo ScrEdit's feature control switches are being set for this program. If you are unsure of what the function of these variables are, look them up in the user manual. There will also be more Page T-3.18 examples of how they work in the section that describes the example data entry screen. -------------------------------------------------------------- Okay, turn back to the "PROGRAM BEGINS HERE" marker. Next We see the procedure Read_Menu_Screen is performed. Read_Menu_Screen. ------------------------------------------------------------- First we will look just at how the menu section works, then we will take a look at each of the menu options. - We see first that the screen "Demo_Menu" is opened and displayed on the video. - The menu option variable is set to 1. - A repeat/until (Pascal) or do/while (C) loop begins that will end when the escape key is pressed ("S_ESC" tests TRUE). - The menu options that you can see on your screen are moved to the screen buffer. - Next we see OPTION is tested for a valid setting. This is where the floating pointer "==>" is made to "wrap" around from the top menu option to the bottom menu option, or from the bottom to top when the OPTION field has been incremented to a value greater or less than the actual number of menu options in the option window. - Next we see that the "P" fields on our screens are being reset to blanks. One of these fields will contain the "==>" pointer that moves up and down the menu list. This field must be reset to blank before the pointer "==>" is moved into the next position or our menu would end up with more that one pointer showing on the screen at the same time. - Next is a case statement (Pascal) or switch statement (C) that is loading the option description that corresponds to the current menu option pointed to by OPTION. Notice also that the "==>" pointer is moved back to the "P" field that corresponds to value of OPTION. - (Turbo C example) After the Screen has been loaded with the current values for the current option, a call to S_ResetKeyFlags re-sets all the global key indicators. In this case we will most likely be resetting the up or down arrow key indicators. - You will notice here that the next statement is another repeat/until statement (pascal) or a while/do statement (C), and you will also notice that this loop will continue until the <ESCAPE>, <ENTER>, or any of the other special keys have been pressed. Page T-3.19 if we did not call S_ResetKeyFlags, C version only, any one of these key indicator may be set to a value of TRUE so the loop would never be perform and our program would go into a infinite loop. - Inside this next loop we see a call S_ReadKey and the program waits here for a key to be pressed. This is where the program that is running on your system is right now. - Next we see an "IF" statements that is only true if the ENTER key, UP ARROW key, or DOWN ARROW key is pressed. If you look ahead in the code to the ELSE condition for the first "IF", you will see where a message is issued telling the user that a invalid keys has been pressed and what keys the program expects. PRESS SOME KEYS TO SEE HOW THE PROGRAM DISPLAYS THE MESSAGE. The second two "IF" statements are testing for the UP, or DOWN arrow keys. Notice the next two "IF" statements that are testing the "PgUp" and "PgDn" key indicator status. PRESS THE <DOWN ARROW> KEY ON YOUR KEYBOARD SEVERAL TIMES. Notice that the pointer ("==>") moves down each time you press the down arrow key. You can see in the code that when S_DOWN tests true the variable OPTION is decremented by 1. Keep pressing the down arrow until the light bar "wraps" back around to the top line of the option window. Next try the UP ARROW and see how it works the same way only in the other direction. Each time you press a key, this inner repeat/until or while/do loop is satisfied and the program goes clear back to the beginning of the procedure where it check the value of OPTION and then loads the screen with the next menu option description. Next notice the if statement that is checking for the ENTER key. When the ENTER key has been pressed then the program begins checking to see which option it is to branch to and execute. That describes the way the menu routine works. Next will we begin looking at each of the menu options. Page T-3.20 Menu Option 1 (an example data entry screen). ----------------------------------------------------------------- The most common use of Turbo ScrEdit is to develop a data entry screen quickly and efficiently. This example will give you a example of how to use all the data entry features of Turbo ScrEdit, as well as how to use many other features. Lets take a look at it. MOVE THE POINTER ("==>") TO THE FIRST MENU OPTION. Place a marker in the listing at this point so you will be able to locate your place when we return from examining how this option works. PRESS ENTER. The demonstration data entry screen is now on your display. RecordDemo ----------------------------------------------------------------- Flip back to the first page of the source listing and we will pick up the program flow in the section marked "MENU OPTION 1". First lets scan through this section and quickly review all the procedures that make up this part of the demo program. First is RecordDemo_Init. Next is a function MakeMsg. Next is the procedure EnterRecords. Next is the procedure RecordDemo; Lets pick up the program flow as it enters RecordDemo. First thing we find is a call to RecordDemo_Init. So.. flip back in the program to RecordDemo_Init. There are some important things to see in this routine. RecordDemo_Init -------------------------------------------------------------- - The first thing inside of the initialization routine is a call to the screen initialization procedure. - Next we see a group of variables are set to null strings and zeros. These fields are going to be where we store the data that we enter into the screen during this demo. Normally you would store the data you enter in a file on the disk. You will notice that this screen has two sections that have fields labeled for name and address. The top one is intended to act like a record for our demo, and will also demonstrate how "display only" fields can be used. - Next the screen "Dupe_Fields" is loaded. Page T-3.21 S_ClearScreen and SET statements. ------------------------------------------------------------ - Next the screen is cleared with a call to S_ClearScreen(1). The "1" used as the argument for the call tells Turbo ScrEdit to set all fields to there initial values as specified in field processing statements. Look at the first field, "DATE", in the screen listing of "Dupe_Fields". See the SET 'SYSDATE' statement on the line below the field. This statement tell Turbo ScrEdit to place the system date in this field each time the screen is cleared using S_ClearScreen. Thus you see a date displayed at the top of the screen. Also look on the second page of the screen listing at the field "NAME2." This field has three processing statements assigned to it. The first is a "help" statement. TYPE ? The "HELP" message defined for this field has appeared on the bottom line of the screen. Any data entry field can have a "help" message associated to it. If you glance through the screen listing you will see that all the data entry fields have help statements defined for them. Next we see a "EDIT" statement. Notice that the "mask" portion of the edit statement is made up of "$" and "4" characters separated by some spaces and a comma. PRESS "X" and fill the entire field with X's. Notice the effect that the edit mask has. When you tried to type into the portion of the field where the comma or spaces are, the cursor skips over them. Those characters are "edited" into the field because of the edit mask. Also try deleting characters. in the last, first, and middle name sections of the field. Notice how the edit mask efects that way that characters are deleted from the field. Next we see that the field has a "SET" statement that assigns the literal "Last , First Mid" to the screen. What I really want you to notice here is how the "SET" and "EDIT" mask are use together on this field. You might use the same concept on a data entry date field: SET 'SYSDATE' EDIT '33/##/3333' DATE MM/DD/YYYY In this example the field is initialized with the system date. If your user changes the date, the edit mask will only accept numeric characters in the month, day, and year portion of the field. Then the DATE statement will verify that the date keyed contains valid month and day values (includeing leap year conciderations.) Page T-3.22 Also locate the field "GROSS2" and it's "SET" statement. You will notice how this "SET" statement has effected the field "Annual Gross" on the screen. - Control exits back to the procedure "RecordDemo". Back in RecordDemo, we see a loop begins that will continue until the ESCAPE key is pressed. Each time through the loop the procedure "EnterRecords" is performed. Flip back in the code to this procedure. EnterRecords ----------------------------------------------------------------- Skip over the first "IF" statement that you see here and locate the call to "S_ReadScreen". This is where the program on the screen is busy scanning the key board waiting for us to press a key or type a value. This portion of the ScrDemo program is to function as a model date entry screen. We see the screen could be divided into three sections. The bottom section of the screen contains the function key labels. Each key has been assigned a special function that will demonstrate one of Turbo ScrEdit's features. The middle section of the screen is the data entry section. We will key data into these fields and be able to experiment with the data entry and editing features of Turbo ScrEdit. The top section of the screen will be our one record file for storing the data that we key in. First lets look at doing simple data entry. In the bottom line of function key labels notice the label associated to the ENTER key reads "Accept Record". PRESS ENTER Turbo ScrEdit processed the screens field validation statements and has located an error condition. The cursor has advanced to the "CITY" field and has displayed a message "Expected Tulare or Pocatello". Look up the "City2" in the screen listing and see the processing statements assigned to it. We see that only one of the two city names will be accepted in this field. TYPE one of the valid city names. PRESS ENTER. Next we see that "State" must also have a value keyed into it, and that it must be "CA" or "ID". Page T-3.23 TYPE one of the valid state abbreviations. GO AHEAD AND TYPE VALUES INTO ANY OF THE OTHER FIELDS ON THE SCREEN THAT YOU WISH. ESPECIALLY NOTICE HOW THE EDIT MASKS EFFECT KEYING DATA INTO THE ZIP CODE FIELD, PHONE NUMBER FIELD, AND SOCIAL SECURITY FIELD. PRESS ENTER. This time the screen has been re-initialized and the values that were in our data entry screen when we pressed enter have been stored in the upper portion of the screen. Lets look at what the program did when we pressed the ENTER key. When we pressed "ENTER" control returned from "S_ReadScreen" and proceeded through our code. This first "IF" statement is ignored because we did not press the CTRL key. The "WHILE" statement is skipped because the ENTER key is not included in the listed of keys that it is testing for. Skip past the "IF" statements testing for function keys in S_F1, S_F2, S_F3, S_F4, S_F5, S_F9, and S_F10 The last "IF" statement in this procedure is testing for two conditions that include the "ENTER" statement. We are now interested in the first condition where the global variable S_EnterAsTab is false, and S_Enter is true. First we see that the values keyed into data entry fields are copied into the global variables that we initialzed earlier in the the initialization routine that are not defined in the screen record. Next we see a call to S_ClearScreen is performed with a "1" argument. This cleared all the fields on the screen and re- assigned the initial values as per any "SET" statements that were defined for the screen fields. Next the data that we stored in the global variables is moved back into fields in the top portion of the screen. S_Point is set to point to the name field on the screen. Control now exits this procedure and returns to the procedure RecordDemo. Since we are in a loop in RecordDemo that won't end until the ESCAPE key is pressed, control goes back to EnterRecords again and ends up back at S_ReadScreen. On the screen we see that the data entry area has been cleared and the data that we typed in is now in the top portion of the screen. Page T-3.24 S_EnterAsTab ---------------------------------------------------------------- Normally Turbo ScrEdit uses the TAB key to move the cursor form field to field and the ENTER key to signal that the screen is ready to be processed. Several users requested that the ENTER key be made to act more like the TAB key. That is when enter is pressed the cursor just advances to the next field. So we added S_EnterAsTab. Notice the F9 key label reads "Toggle Accept Key." and next to it the ENTER key label reads "Accept Record". PRESS F9 Notice that the ENTER key label has now changed to the F10 key label. PRESS ENTER SEVERAL TIMES and watch the cursor. Now the cursor moves from field to field just as though the TAB key is being pressed. As far as Turbo ScrEdit is concerned the ENTER and TAB keys are the same keys. PRESS F10 The F10 key now has the same effect that the ENTER key had before. TYPE DATA INTO THE SCREEN FIELDS (use the ENTER and TAB keys to advance from field to field) AND PRESS F10 AGAIN. If you took the time to fill in several fields and re-key the city and state fields, when you pressed the F10 key the data you keyed moved to the top portion of the screen just as it did in the previous example when the ENTER key was pressed. First locate the "IF" statement at the very beginning of the EnterRecords procedure. This "IF" statement moves the value "ENTER" or "F10" to the function key label for "Accept Record". PRESS F9 several times and notice how the label changes. Next Locate the "IF" statement that is testing "S_F9". When user has pressed the F9 key and S_F9 tests true, the value of S_EnterAsTab is toggled to its opposite value. Next notice in the procedure the handled the ENTER key that it's second condition or "OR" condition is set for when "S_EnterAsTab" tests true and the F10 key has been pressed. Before you try to use the ENTER AS TAB option in your program, be sure to look up and read about S_EnterAsTab in the programmers reference manual. Page T-3.25 One of the major differences is that Turbo ScrEdit will no longer automatically perform field validation. Instead you will have to call the validation procedure yourself. Look at the "IF" statement just above the one that processed our ENTER and F10 keys. Here you see what is required to perform screen field validation when you are using ENTER as TAB. The global variable S_ScreenValid is set to TRUE just before S_ValidateScreen is performed. If S_ScreenValid is still TRUE when control returns from S_ValidScreen, then the screen has good data in its fields. If S_ScreenValid is FALSE when control returns, S_Point be set to the field number of the offending field. We reset all our key indicator fields so no further processing will be done, particularly the ENTER or F10 key processing. Then control returns back to the top of this procedure and drops into S_ReadScreen. Turbo ScrEdit then displays the field error message and place the cursor on the field with bad data. Dupe Fields (S_IsDupe, S_SetDupe, S_ClearDupes) ----------------------------------------------------------------- Next lets look at the advantage of using DUPE fields. Locate the function key labels for F1 and F2. We see F1 reads "Set/Clear Dupe Fields" and F2 reads "Clear All Dupe Flds". Dupe fields are very useful for fields like city and state. TYPE a valid value into CITY but do not press ENTER or TAB. Leave the cursor in the CITY field. Press F1 When you pressed the F1 key a pair of brackets appeared to both sides of the field. I have programmed this screen to use these brackets to indicate when a field is in DUPE MODE. These brackets are not required, and have no effect on how this program will work. The brackets are just the way I have chosen to help you be able to see which of the fields is set to DUPE status. Do the same for the STATE field: Now you should have valid values in the city and state fields. Press the tab key so the cursor moves all the way around the screen to the second line of address. (Do not use the SHIFT TAB yet, just use TAB.) At this point your cursor is blinking in the field directly above CITY field. WATCH THE CURSOR AS YOU PRESS THE TAB KEY AGAIN. Dupe fields are skipped as the cursor advances "forward" from field to field. Page T-3.26 Changing the value of a DUPE FIELD. ----------------------------------------------------------------- If you need to change the value of a DUPE field you can do so by using SHIFT and TAB to move the cursor backwards into the field. You can then type a new value into the field. When the cursor exits the field the new value will become the dupe value. TYPE date into the other fields on the screen. PRESS ENTER (or F10 depending on the mode that your screen is in). This time when the data was moved up on the screen and the screen fields were cleared, the CITY and STATE fields retained their values. Lets look at the coding that sets dupe fields. Locate the "IF" statements that test "S_F1". First in this logic we see S_IsDupe is used to check the DUPE status of the current field. This function will return TRUE if the field is a DUPE field or FALSE if the field is a regular data entry or display only field. In this example if the current data entry field is not a DUPE field so the program calls S_SetDupe three times to set the bracket fields and the current field to DUPE status. ** IMPORTANT CONCEPT ** Notice the order that the fields are being set to dupe status. If we were to set the bracket fields to dupe status AFTER we set the current field to dupe status, the cursor would advance out of the current field to the next data entry field on the screen. This is because Turbo ScrEdit has to do some special processing to allow the field to remain in the dupe field. So always set the dupe status for the data entry field you want the cursor to be in LAST when you are setting DUPE status for more than one field. Notice that the two other fields that are used to display the brackets are also set to dupe fields. Next is a switch or case statement that determines which field the cursor was on when the F1 key was pressed and places brackets in the fields around it. Use SHIFT and TAB to move the cursor backwards into one of our dupe fields. PRESS F1 again. Notice that the brackets disappear and the field is set back to a regular data entry field status. Locate the ELSE condition of the "IF" statement that test the field status using S_IsDupe. This routine uses S_ReSetDupe to reset the field to it's original field data entry type, and blanks out the brackets. Page T-3.27 As I mentioned earlier, the brackets that I am using on the screens are optional. In your programs you will probably not want to place brackets around the DUPE fields like I have done here. If that were so, you could condense this whole routine down to: Pascal C ------------------------------- ------------------------------ If S_F1 Then if (S_F1) Begin { If S_IsDupe(S_PrevFld) Then if (S_IsDupe(S_PrevFld)) S_SetDupe(S_PrevFld) S_SetDupe(S_PrevFld); Else else S_ResetDupe(S_PrevFld); S_ReSetDupe(S_PrevFld); End; } The above examples would cause the DUPE fields to act just the same as they do now except the brackets would not be used on the screen. The user of your program will know when he encouters a DUPE field because the cursor will skip over it. Next Set all the fields on the screen to DUPE status. Notice when you tried to set the last field to dupe that Turbo ScrEdit would not let you. At least one field must remain a data entry field. Now lets clear all the dupe fields set on the screen at once. PRESS F2 Locate the F2 if statement and you will see it calls S_ClearDupes. S_ClearScreen resets all screen fields back to their original status. The remainder of this routine removes the brackets that may be on the screen by blanking out all the bracket fields. Sound ON/OFF ----------------------------------------------------------------- Locate the F3 function key label that reads "On/Off Sound". This key will toggle sound mode on and off. Locate the "IF" statement that tests for S_F3 TRUE. In this example I am testing the value S_HelpSound. When F3 has been pressed and S_HelpSound is set to TRUE, then sound is turned OFF by setting the different message line sound flags to FALSE. The opposite logic is used to turn sound back on. In your programs you can set and reset any of the sound variables indepent of each other. You may want to turn sound off for the help messages by setting S_HelpSound to FALSE, and leave sound on for error messages (S_ErrorSound) and user generated message (S_UserSound.). Try pressing the ENTER key a few times while using the F3 key to toggle sound on and off. Page T-3.28 Auto Help ON/OFF ---------------------------------------------------------------- You will recall that keying a ? mark into any of the data entry fields will cause a help message to appear on the bottom line of the screen. One of our user asked that the help messages be made to display automatically when the field was edited. It sound like a good idea so we created the S_AutoHelp message logic. Locate the F4 function key label. This key will demonstrate using the "AutoHelp" feature. With "AutoHelp" active, the field help messages will be displayed each time cursor moves from field to field. First look up the "IF" statement that test "S_F4". You will see that this procedure is toggling the global field "S_AutoHelp" on and off. PRESS F4 PRESS TAB to move the cursor from field to field. Notice that each time the cursor enters a field it displays that fields help message. The message will disappear when the next key is pressed. PRESS F4 to turn off "Auto Help". Auto Validate ON/OFF ---------------------------------------------------------------- Again we had a user request that field validation could occur at the time that data was entered into a field. That also sounded like a pretty good idea.. so we introduced the "Auto Validate" logic. Locate the F5 function key label that reads "On/Off Auto Val". This procedure demonstrates using Turbo ScrEdit's Auto Validate option. Normally field validation occurs when the ENTER key is pressed. And then the entire screen is validated at one time. Using this option you can force Turbo ScrEdit to validate the contents of the current data entry field just before the cursor moves out of it to a new field. PRESS F5 PRESS TAB to move the cursor around the fields on the screen. The cursor should stop when you get to the City field and the familiar message will appear on the message line. Locate the F6 function key label that reads "Edit Last Entry". This procedure just moves the field values from the top portion of the screen down into the edit fields of the screen. Page T-3.29 Changing Message line Colors ----------------------------------------------------------------- Next locate the "while" statement that is conditioned depending on the values of HOME, END, UP ARROW, DOWN ARROW, PGUP, and PGDN keys. This routine demonstrates how to change the colors used for displaying messages. Turbo ScrEdit provides three message fields. You will normally use only the "S_UserMsg" fields in your programs. Turbo ScrEdit uses "S_ErrorMsg" and "S_HelpMsg". Even though you won't use the other two fields, you will want to control the colors that are used to display their messages. If you look inside the "while" loop you will see that first a message provided by the function "MakeMsg" is moved into the message field that corresponds to the key that was pressed. If you look back into the coding of the "MakeMsg" function you will see that it converts background and foreground color codes into text and builds a message line that includes the current settings. Next you will see a call to S_ReadKey. Next you will see where the background and foreground color fields for each of the message fields is being incremented depending on which keys are pressed. Now go ahead and try pressing the keys. The purpose of this example is to demonstrate that by changing the values of S_HelpBg or S_HelpFg you will change the color that is used when S_HelpMsg is displayed. The same holds true for S_ErrorBg, S_ErrorFg, and S_ErrorMsg. This allows you to control the colors used by Turbo ScrEdit when it displays messages. Likewise, you can control how the messages that you move to S_UserMsg are displayed by changing the color assignments of S_UserBg and S_UserFg. PRESS ESC Control now drops out of the loop we began in the procedure RecordDemo. Before we exit this procedure and return to the main menu we see some house keeping is being performed. Most of this is just getting things in order for the next time that we call this procedure. Well that ends the discussion of Option 1 - A data entry example. We now return to our menu to pick up with Option 2. Page T-3.30 Menu Option 2 (Demo of Mouse Functions). ----------------------------------------------------------------- Skip this section if you do not have a mouse. If you do have a mouse and your mouse driver has not been loaded into memory, exit now to the dos prompt and load your mouse driver. Return now to the main menu portion of the code and locate where OPTION 2 is being performed. Press the DOWN ARROW key to place the menu pointer next to "Demo of Mouse Functions" label on the menu. S_MouseInstalled ----------------------------------------------------------------- The first thing we see as the menu begins to process option 2, is an "IF" statement testing the TRUE/FALSE status of the global variable S_MouseInstalled. During program initialization, the mouse initialization procedure checks to see if the mouse driver is loaded into memory. If no mouse driver is found, S_MouseInstalled is set to FALSE. In our program example, the mouse driver has not been found in memory, the "ELSE" condition is performed and a error message is moved to the S_ErrorMsg field. When the mouse driver is present, the mouse demo screen is loaded and control branches to the mouse demo routine. When control returns from the mouse demo routine the main menu screen is reloaded. PRESS ENTER The mouse demonstration screen is now displayed on the screen. Locate the routine MouseDemo in our source code example. S_ActivateMouse ---------------------------------------------------------------- S_ActivateMouse is the first procedure called when you wish to begin interacting with the mouse driver. This procedure could be said to "turn the mouse driver on". All call to the mouse procedures will be ignored until the mouse driver is activated. S_SetMouseEvent ----------------------------------------------------------------- When the mouse system is initialized, the mouse driver is started in neutral, so to speak. The mouse driver is monitoring the mouse but will not interupt our program. Before we can get any information from the mouse driver we must tell it what information we want it to report to our program. Next We see S_SetMouseEvent is called and that the contents of one of the Page T-3.31 screen fields is being passed as the argument. If you look in the lower right hand corner of the screen you will see the contents of the field that is being passed. It holds a string of 1's and 0's, "01111110". Each of these characters represent the status of a bit in a single byte field that is passed to the mouse driver. Each of the bits represents a mouse activity that the mouse driver will use as a trigger to know when to interrupt our program and pass the current status of the mouse to our program. In the discussion that follows you will see how different bit patterns effect how the mouse driver acts. TAKE A MOMENT HERE AND LOOK UP "S_SetMouseEvent" IN THE MOUSE SECTION OF THE PROGRAMMERS REFERENCE MANUAL. There you will find a description of the bit mask and which mouse functions each bit effects. We will also discuss this subject in more detail a little later in this section. S_SetMouseRange ----------------------------------------------------------------- By default the mouse cursor can be moved anywhere on the screen. This procedure allow you to "fence" the mouse in by specifying a "mouse window". If you look in the "Current Mouse Activity" section of the screen and locate the section titled "Mouse Window". Notice that it has labels for "row" and "column" and "upper left" and "lower right". These fields indicate the current mouse window. If you move the mouse up and down, and left and right, you will see that it will not move out of the area defined here as the "Mouse Window". S_MsRow and S_MsCol ----------------------------------------------------------------- These fields have two purposes. First they report to your the mouse cursor location when the last event occurred. Second the can be used to relocate the mouse on the screen. S_ShowMouse ----------------------------------------------------------------- This procedure is what makes the mouse cursor visible on the screen. When the mouse cursor is made visible on the screen it will be at the row and column position specified in S_MsRow and S_MsCol. If the values of S_MsRow and S_MsCol would place the mouse cursor outside of the current mouse window, the row and column are adjusted to row 1 and column 1 of the current mouse window. Next control drops into a loop. Flip ahead in the code and look at the conditions that the loop will end. We see here that the loop will end when the LEFT MOUSE BUTTON is pressed and the cursor is somewhere between columns 1 and 5 on row 11 of the screen. Page T-3.32 If you were to plot the locations on the screen you would find that it is located in one of the three highlighted characters next to the description for option four "Return to Demo Menu" of the mouse demo menu. Now turn back to where control enters the loop. The first thing that is done here is the coordinates for the current mouse window is moved to the screen fields in the "Mouse Window" section, and the "Current Cursor Row Col" section is updated with the row and column position of the mouse cursor as of the last occurrence of a mouse event. S_ResetMouseFlags ---------------------------------------------------------------- There are six mouse button indicators that are used so your program can detect which of the mouse buttons have been pressed or released. After you have analyzed their status and are done processing them you must reset them. *** IMPORTANT CONCEPT *** If you do not call this procedure to reset the button indicator status, they will remain set to TRUE, or will continue to indicate that a button was pressed that really was not pressed during the last mouse event. S_ReadKey ---------------------------------------------------------------- This is where the program is now. It has branched into the Turbo ScrEdit user interface and is busy scanning the keyboard waiting for a key to be pressed or a mouse event to occur. S_MouseEvent (S_Ms->MouseEvent in C) and S_AnalyzeMouse ----------------------------------------------------------------- When a mouse event occurs, the mouse driver interrupts our program just as a pop up utility would interrupt your program. For just a fraction of a second, the mouse driver calls a routine in the mouse interface and passes it the current status of the mouse. This routine stores the data passed by the mouse driver and set the global variable "S_MouseEvent" to TRUE. It then returns control to the mouse driver which returns control back to our program. Turbo ScrEdit detects that a mouse event has occurred because S_MouseEvent now test TRUE, so it returns control back to our program just as it does when the ENTER key or one of the function keys is pressed. Next in our code we see an "IF" statement that is testing to see if a mouse event has occurred. If a event has occurred the Page T-3.33 procedure "S_AnalizeMouse" is called. This routine analyzes the data passed to our program and sets other global variables to indicate what buttons were pressed or released, and the current row and column of the mouse cursor. The last thing that this routine does is set the "S_MouseEvent" variable to FALSE. *** IMPORTANT CONCEPT *** When a mouse event has occurred, you must call S_AnalizeMouse before the next call to S_ReadKey, S_NextKey, S_ReadScreen, or S_ReadField. YOUR PROGRAM WILL GO INTO A INFINITE LOOP IF YOU DO NOT. ONCE S_MouseEvent IS SET TO TRUE, ONLY A CALL TO S_AnalizeMouse CAN RESET IT TO FALSE. BECAUSE S_MouseEvent IS SET TO TRUE, THE KEYBOARD SCAN ROUTINE WILL THINK THAT A MOUSE EVENT HAS OCCURRED SO IT WILL NOT STOP AND WAIT FOR A KEY TO BE PRESSED. IT WILL JUST RETURN CONTROL TO YOUR PROGRAM. YOUR PROGRAM WILL NOT BE ABLE TO TELL THAT A MOUSE BUTTON WAS PRESSED BECAUSE THE MOUSE DATA WAS NOT ANALYZED AND MADE AVAILABLE TO YOUR PROGRAM... SO.. YOU PROGRAM WILL HANG. Now that we have discussed the basics on communicating with the mouse lets take a look at how each of the parts of this demo works. Move the mouse cursor as far down on the screen as it will move. PRESS THE LEFT MOUSE BUTTON DOWN AND HOLD IT. Notice in the lower left side of the screen that the a message "*Pressed*" has appeared beneath the label "Left Button". Also notice that the "Current Cursor Row and Column" section has been updated with the screen coordinates of the cursor when the button was pressed. RELEASE THE LEFT MOUSE BUTTON Now the message has changed to "*Released*". TRY PRESSING AND RELEASING THE OTHER BUTTONS ON YOUR MOUSE. Next lets look at the logic that causes the pressed and released messages to appear on the screen. After control returns from S_ReadKey, the mouse event is analyzed and our global variables are set to indicate the mouse activity. Next we see the routine "Set_Button_Labels" is performed. Locate the routine, it is the first routine in the mouse section of the listing. Page T-3.34 Set_Button_Labels ----------------------------------------------------------------- In this routine we see a series of "IF" statements that test the status of the mouse button indicator fields. If the button has been pressed the "*Pressed*" message is moved to the screen field. If the button has been released the "*Released*" message is moved to the screen field. If no activity occurred for the button the screen field is blanked out. The main thing that I want you to see here is how the mouse button status is tested. Next control exits this routine and returns to the mouse demo procedure. Next, as control returns from "Set_Button_Status", we see an "IF" statement. We did not press the LEFT MOUSE BUTTON in one of the specified screen positions so control advances to the "ELSE" clause. Again the case statement does not effect us so control returns to the top of the procedure, screen fields are updated, mouse button indicators are reset, and control passes back to S_ReadKey. Now turn your attention to the top section of the screen labeled the "Mouse Event Handler Set Up". Notice here that all the mouse activities that our program seems to detect are described in highlighted fields in this section. Next we will change the events that the mouse driver will monitor for. MOVE THE MOUSE CURSOR TO THE HIGHLIGHTED 1 NEXT TO THE MENU OPTION "Modify Event Handler". PRESS THE LEFT MOUSE BUTTON. A new label has appear in the top section of the screen that reads "** Finished **" and the mouse cursor has been placed in the middle of the new field. Lets take a look at the code that just handled what we have done. As control returned from S_ReadKey the mouse event was analyzed. The button status was updated on the screen. The "IF" statement is still false because our cursor was not in the specified areas of the screen so control moves to the "ELSE" clause. In the ELSE clause we see that when the cursor is in rows 5, 7, or 9 that the routine "Change_Mode" is performed. Our cursor was in row 5 so we branch to the routine "Change_Mode". Page T-3.35 Change_Mode ---------------------------------------------------------------- Locate this routine in the source listing. The first two "IF" statements in this routine are skipped because our cursor was on row 5 five of the screen when we clicked the left mouse button, so S_MsRow will have a value of 5. We see that we match the criteria described in the third "IF" statement. Inside this "IF" statement we see that the field display color attributes are being changed for field number 5 on the screen, number 4 for C, (Remember Turbo ScrEdit numbers the screen fields left to right top to bottom). Next we see the "finished" message is moved into the screen field. Next we see the current mouse window is changed to the top portion of the screen. Next the Row and Column fields as assigned new values and the mouse cursor is moved into the fields with a call to S_MoveMouse. Control then exits this procedure and we see the mouse cursor setting in the "finished" field in the top section of our screen. MOVE THE MOUSE CURSOR UP TO THE ONLY LABEL THAT IS NOT HIGHLIGHTED "Cursor MoveMent" AND PRESS THE LEFT MOUSE BUTTON. The "Cursor Movement" label has become highlighted, and if you look at the bit pattern in the lower right section of the screen you will see it has changed. The first character was a 0 and is now a 1. Keep your eye on the bit pattern as you do the next few items outlined here. MOVE THE CURSOR TO "Left Released" AND PRESS THE LEFT BUTTON. The "Left Released" label changed to normal text on a black background. Notice that the bit patter has changed again. The third character changed from a 1 to a 0. REPEAT THE ABOVE ON EACH OF THE "RELEASED" FIELDS SO ONLY CURSOR MOVEMENT AND BUTTON PRESSED LABELS ARE HIGHLIGHTED. MOVE THE MOUSE CURSOR TO THE "FINISHED" LABEL AND PRESS THE LEFT MOUSE BUTTON. Now the mouse cursor has moved back to the 1 in the first menu option. We can see by the highlighted labels in the top section that the mouse driver should now only interrupt our program if the cursor moves or if one of the buttons is pressed. Lets take a look at the code that just handled what we have done. Page T-3.36 Each time we pressed the mouse button on one of the activities described in the top section of the screen, control passed down to the "ELSE" section of the "IF" statement in the main menu code. This time the current row was in the range specified in the case statement that caused control to branch to the "Set_Event_Mask" routine. Set_Event_Mask ----------------------------------------------------------------- In this routine, you will find a "IF" statement for each of the eight labels in the top portion of the screen. Lets look at how the first "IF" statement works. Each of these if statements is performed if the cursor was in the specified row and columns of the screen when the LEFT BUTTON was clicked. Inside we find another "IF" statement that is testing the status of the character in the bit pattern that represents the function described in the label where the mouse cursor was. If the bit pattern character was a '0' then the bit pattern character is changed to a '1', or turned on, and the corresponding field's display color attribute is changed to highlighted. If the bit pattern character was a '1' then the bit pattern character is changed to a '0' and the corresponding field's display color is changed to cyan text on a black background. There are eight "IF" statements in this section of code, but only one of them will be performed each time this routine is called. Control returns back to the main menu section and drops back around to S_ReadKey. On the screen we see the labels change color as we click the mouse button on them, and the bit pattern in the lower right section of the screen changes to reflect the activities that we select or de-select. Finally, we clicked our mouse button while our cursor was on the "finished" label. Control returned from S_ReadKey and the mouse event was analyzed. The button labels were set, and, this time, we see that the cursor position satisfies the third condition of the the main "IF" statement. So control entered inside the statement part of the "IF". Inside we see that: The "Mouse Window" is set reset to the mouse menu portion of the screen. Next, because S_MsRow has a value of 3, the display color attribute for field number 5 (4 for C) is reset to green (2) on black (0). Page T-3.37 Next, the finished field is blanked out. Next, the bit mask that we see in the lower right hand corner of the screen is used as the argument to the call to S_SetMouseEvent. This call establishes our new selections as the current mouse activity that the mouse driver will monitor for. Next, the mouse is move back to column 3 and row 5, which happens to be the 1 character in the highlighted area next to the "Modify Event Handler" menu option. Control then zips through the remainder of this routine and falls back to S_ReadKey. Keep your eye on the row and column values in the "Current Cursor Row and Column" section of the screen and move the mouse cursor around on the screen. As the cursor moves the row and column values change. These row and column values can be used for dragging windows around on the screen, plotting a line, etc. PRESS THE MOUSE BUTTONS AND SEE HOW THE NEW EVENT HANDLER ACTS DIFFERENTLY. This time the "*Pressed*" label stays on the screen until the mouse is moved or another key is pressed. The mouse driver is no longer interrupting our program when a key is released. Try tracing through the code for options 3 and 4. They are simple options that just show more of changing the mouse window and positioning the cursor. And that ends the discussion on using the mouse interface. You should now be armed with enough insite to develop your own point and click programs. BE SURE TO READ THE SECTION OF THE MOUSE USER MANUAL ENTITLED "A word to the wise about using mouse procedures." on page M-1 of the programmers reference manual. Also experiment with the mouse demonstration program "TestMous.C" or "TestMous.Pas" that was included in your Turbo ScrEdit package. Now lets follow the code as we exit the mouse demo and return to the main menu. PLACE THE MOUSE CURSOR ON THE 4 IN OPTION 4 OF THE MOUSE MENU AND CLICK THE LEFT MOUSE BUTTON. In the code we see that clicking on option 4 ends the main loop of the mouse routine so control drop out and heads for the routine exit. As it falls through the code see: First, all mouse flags are reset. Page T-3.38 S_HideMouse ----------------------------------------------------------------- This routine makes the mouse cursor invisible on the screen. Even though the cursor is not on the screen, the mouse driver is still busy monitoring the mouse. Mouse events will still be handled just as when the mouse cursor was visible. S_DisableMouse ----------------------------------------------------------------- This routine puts the mouse driver to sleep. It stores the current event bit pattern and sends the mouse driver a bit pattern of "00000000", which means "don't monitor any mouse activity. The mouse driver will do nothing until a new bit pattern establishes a new activity list. And finally control returns to the programs main menu. The menu screen is reloaded and is restored just as it was when we branched to the mouse demo routine. Menu Option 3 (Customizing screen colors.). ----------------------------------------------------------------- Turbo ScrEdit now allows you to change any color assignments to any portion of the screen by using the procedure S_ChangeScreenColor. The color assignments for any of the fields can also be changed by using S_ChangeFieldColor. Before we begin take a moment and look these two procedures, "S_ChangeScreenColor" and "S_ChangeFieldColor", up in the programmers reference manual . The descriptions there will give you a good overview of how these statements work. Now locate where menu Option 3 is being processed in the main menu section of the screen. Here we see that the screen "Color_Demo" is being initialized by a call to "Initialize_Color_Demo_Buf" each time this option is performed. Next we see that the screen "Color_Demo" is loaded and displayed on the screen. Next control branches to the procedure "ChangeColors". When control returns from "ChangeColors" the menus screen will be reloaded and re-displayed. Page T-3.39 Locate the routine "ChangeColors" in your program listing in the section marked: ********************************* MENU OPTION 3 (Customizing Screen Colors) Section 4 of Turbo ScrEdit Tutor Part III. ********************************* As control enters this routine we see that the screen fields are assigned the default values that describe the current colors used on the screen. Next we drop into a "while" loop that will continue until the ESCAPE key is pressed. Next a call to S_ReadScreen is performed. This is where our program is at right now. The cursor is setting on the first field in the data entry window on the line labeled "Screen background". Before we begin lets take a look at the code and see what is going to happen when we begin using this demonstration. S_ChangeScreenColors ---------------------------------------------------------------- The next several lines of code that we going to look at perform calls to S_ChangeScreenColor. Lets look at the meaning of the parameters being passed by the first example. It is using the following parameters that mean: 0 - The zero here means change the color assignments for all characters in the specified area of the screen. If you looked this up in the manual you read that this option can be any value between 0 and 3: 0 means change all characters, 1 means change only single line characters, 2 means change only double line characters, 3 means change only block line drawing characters. Color_Demo_Buf.A - Passes the background color to be assigned. Color_Demo_Buf.F1 - Passes the foreground color to be assigned. 1, 24, 1,80 - Specifies the "window" of the screen that is to be changed in the format of TOP ROW, TOP COLUMN, BOTTOM ROW, BOTTOM COLUMN. Page T-3.40 You will find similar statements in each of the sections that follow the section marked "Text". Notice that the screen has been divided into sections where: Text Changes every character on the screen. Double line around logo Changes only the double line drawing characters that it finds in the to 11 lines of the screen. Logo Changes only the double line characters in the screen area that surrounds the word "ScrEdit". Fill in Logo Letters This group of statements changes the colors of all the spaces that are embedded in the logo "ScrEdit". Other logo text This group of statements updates the color assignments for "TM", "Turbo", and the text "The Screen Editor for Turbo Pascal Programmers". Copyright Notice Changes the colors of the copyright notice. Version Number Changes the color of the version number. Text in configure box Changes the color of the text inside the single line box where we will be keying in new color values. Single line box Changes the color of the single line box that surrounds the text for the data entry section of the screen. S_ChangeFieldColor ----------------------------------------------------------------- Next we see a loop that will change the prompt and display color assignments for the data entry fields on the screen. Lets take a look at the parameters that are being passed in the Page T-3.41 first statement: X Specifies the number of the field that is to have it's color assignment changed. (Remember fields are numbered left to right, top to bottom.) 1 Specifies the field mode that the new color will effect. 0 - Change Normal (empty) display color. 1 - Change Prompt field color. 2 - Change Display color mode. (Field color modes are described in the first part of the tutor.) Color_Demo_Buf.H Specifies the new foreground color for the field mode being changed. Color_Demo_Buf.F8 Specifies the new background color for the field mode being changed. Okay, with that over view let try this option out. TYPE 0 over the 2 in the first field. PRESS TAB TYPE 2 in the background color field. PRESS TAB Type 15 for foreground color on the ScrEdit Logo PRESS ENTER You will notice a brief pause as and the new screen is displayed with the changes applied. S_StoreColorChanges ----------------------------------------------------------------- Normally you will not want to have your program changing the screen colors as the user is using a screen. Rather, you will want to create a "installation" program or a "configuration" routine that allows your user to customize the appearance of a screen and then store the changes permanently. You could make the changes we just performed permanent by coding a call to "S_StoreColorChanges" at the end of this routine. "S_StoreColorChanges" saves the assignments back into the screen library file. That concludes our discussion of changing the color assignments to screens programmatically. Now lets turn back to the main menus section of the program were control returns from "ChangeColors". Page T-3.42 Option 4 and 5 ---------------------------------------------------------------- Menu Options 4 and 5 are used to give you a programming example of using field validation statements. The screen that these options used was thoroughly explained in PART II of the tutor. Option 6 ---------------------------------------------------------------- This option will demonstrate how to use the message line and S_ReadKey to communicate with the user of your programs. When you select this option a message is displayed that reads: "Press 'C' key to continue". If any other key is pressed the user receives the message: "OOPS!! wrong key - Press 'C' key to continue" The program will continue prompting for the user to press a key until he types a upper case "C" character and ScrDemo displays the message: "'C' has been pressed - You may continue." Option 7 ----------------------------------------------------------------- This option demonstrate mixing your languages standard "write" or "cprintf" statement to place text on the screen. Notice here that no message is displayed on the bottom line of the screen. The procedure S_NextKey will only accept a key stroke. It will not display any messages. Option 8 ---------------------------------------------------------------- This option demonstrates how to run a "son" process from a program using Turbo ScrEdit. DemoWind.EXE is a demonstration program that touches on all the features of using Turbo ScrEdit windows. Turbo ScrEdit windows comes with the registered version of Turbo ScrEdit. However I have included the source code for the program DemoWind.Exe so you can examine the coding required to use windows. Option 9 ----------------------------------------------------------------- This procedure is also easy to follow and demonstrates how you might have your program switch back to using normal video I-O for your language, and then switch back to resume processing Turbo ScrEdit's screens. And that concludes the programming portion of Turbo ScrEdit Tutor. **